\documentclass[a4paper,10pt]{article}
\usepackage{fullpage}
\usepackage[british]{babel}
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
%\usepackage{amsthm} \newtheorem{theorem}{Theorem}
\usepackage{color}
\usepackage{float}
\usepackage{todonotes}
\usepackage{caption}
\DeclareCaptionFont{white}{\color{white}}
\DeclareCaptionFormat{listing}{\colorbox{gray}{\parbox{\textwidth}{#1#2#3}}}
\captionsetup[lstlisting]{format=listing,labelfont=white,textfont=white}

\usepackage{alltt}
\usepackage{listings}
 \usepackage{aeguill}
\usepackage{dsfont}
%\usepackage{algorithm}
\usepackage[noend]{algorithm2e}
%\usepackage{algorithmicx}
\usepackage{subfig}
\lstset{% parameters for all code listings
language=Python,
frame=single,
basicstyle=\small, % nothing smaller than \footnotesize, please
tabsize=2,
numbers=left,
% framexleftmargin=2em, % extend frame to include line numbers
%xrightmargin=2em, % extra space to fit 79 characters
breaklines=true,
breakatwhitespace=true,
prebreak={/},
captionpos=b,
columns=fullflexible,
escapeinside={\#*}{\^^M}
}


% Alter some LaTeX defaults for better treatment of figures:
    % See p.105 of "TeX Unbound" for suggested values.
    % See pp. 199-200 of Lamport's "LaTeX" book for details.
    % General parameters, for ALL pages:
    \renewcommand{\topfraction}{0.9}	% max fraction of floats at top
    \renewcommand{\bottomfraction}{0.8}	% max fraction of floats at bottom
    % Parameters for TEXT pages (not float pages):
    \setcounter{topnumber}{2}
    \setcounter{bottomnumber}{2}
    \setcounter{totalnumber}{4} % 2 may work better
    \setcounter{dbltopnumber}{2} % for 2-column pages
    \renewcommand{\dbltopfraction}{0.9}	% fit big float above 2-col. text
    \renewcommand{\textfraction}{0.07}	% allow minimal text w. figs
    % Parameters for FLOAT pages (not text pages):
    \renewcommand{\floatpagefraction}{0.7}	% require fuller float pages
% N.B.: floatpagefraction MUST be less than topfraction !!
    \renewcommand{\dblfloatpagefraction}{0.7}	% require fuller float pages

% remember to use [htp] or [htpb] for placement


\usepackage{fancyvrb}
%\DefineVerbatimEnvironment{code}{Verbatim}{fontsize=\small}
%\DefineVerbatimEnvironment{example}{Verbatim}{fontsize=\small}

\newcommand{\keywords}[1]{\par\addvspace\baselineskip
\noindent\keywordname\enspace\ignorespaces#1}


\usepackage{tikz} \usetikzlibrary{trees}
\usepackage{hyperref} % should always be the last package

% useful colours (use sparingly!):
\newcommand{\blue}[1]{{\color{blue}#1}}
\newcommand{\green}[1]{{\color{green}#1}}
\newcommand{\red}[1]{{\color{red}#1}}

% useful wrappers for algorithmic/Python notation:
\newcommand{\length}[1]{\text{len}(#1)}
\newcommand{\twodots}{\mathinner{\ldotp\ldotp}} % taken from clrscode3e.sty
\newcommand{\Oh}[1]{\mathcal{O}\left(#1\right)}

% useful (wrappers for) math symbols:
\newcommand{\Cardinality}[1]{\left\lvert#1\right\rvert}
%\newcommand{\Cardinality}[1]{\##1}
\newcommand{\Ceiling}[1]{\left\lceil#1\right\rceil}
\newcommand{\Floor}[1]{\left\lfloor#1\right\rfloor}
\newcommand{\Iff}{\Leftrightarrow}
\newcommand{\Implies}{\Rightarrow}
\newcommand{\Intersect}{\cap}
\newcommand{\Sequence}[1]{\left[#1\right]}
\newcommand{\Set}[1]{\left\{#1\right\}}
\newcommand{\SetComp}[2]{\Set{#1\SuchThat#2}}
\newcommand{\SuchThat}{\mid}
\newcommand{\Tuple}[1]{\langle#1\rangle}
\newcommand{\Union}{\cup}
\usetikzlibrary{positioning,shapes,shadows,arrows}

\usepackage{url}


\pagestyle{empty}

\title{Distributed Systems - Spring 2013 \\ System Design Report}

\author{Group 2}

\begin{document}

\maketitle

\section{Introduction}

This report presents the design for Group 2's Distributed Systems project. The project's goal is to implement a distributed system that allows a user to control a robot to explore an environment. It consists of three components, a server, a client and the robot itself. All of the components are implemented in Java, and they use a protocol designed together with the other groups taking the course to ensure interoperability between our systems.

\section{Requirements}

\subsection{Dictionary}

To avoid misinterpretations, the following terms are used for the requirement specification.

\begin{itemize}
	\item Environment: The environment in which the robot is located (table, room, ...).
	\item Current position: The current position of the robot.
	\item Bad position: Positions that will put the robot in an unsafe state (fall over edges, crash into walls), or positions where objects blocking the path.
	\item Safe path: A path through the environment free of known \emph{bad positions}.
	\item Goal position: The end point of a \emph{safe path}.
	\item Mapped position: A position the robot has visited before.
\end{itemize}

\subsection{Requirement specification}

The requirements set up for the robot consists of our own adaptions of the abstract requirements presented at the introduction lecture for the course. The group has also decided to add a few own requirements. The requirement specification, as decided during the Milestone 1 phase, looks as follows:

\begin{enumerate}
	\item The server \emph{should} accept commands from a webpage (client).

	\item The robot \emph{must} be able to approximate its \emph{current position}.

	\item The robot and server \emph{must} be able to communicate \emph{current position}, and a \emph{safe path} to the \emph{goal position}.

	\item The robot \emph{must} be able to move on a reasonably flat area, without entering \emph{bad positions}.


	\item The robot \emph{must} be able to build a map of the environment. It \emph{should} remember where \emph{bad positions} are located.

	\item The robot \emph{should} return to a safe state if communication between robot and server is lost.

	\item The robot or the server \emph{should} be able to calculate and move the robot along a \emph{safe path} through the \emph{environment} to a specified \emph{mapped position}.

	\item The robot \emph{should} update the map when new \emph{bad positions} are discovered.

	\item The robot or server \emph{must} calculate a new safe path if the previous \emph{safe path} is blocked by \emph{bad positions}.
	
	\item The robot \emph{must} be able to communicate and work together with the robot of another group.

\end{enumerate}

The implemented product fulfills most of these requirements, the exception is requirement 6.

\section{Hardware}

The server and client applications are designed to run on any standard PC capable of running a Java Virtual Machine. The robot is built using Lego Mindstorms hardware.

\subsection{Server}

The server hardware requirements are Ethernet, for communication with the Client, and a Bluetooth interface for communication with the robot. It also needs a webcam to be able to send the map and webcam stream to the client.

\subsection{Client}

The only hardware requirement for the client is an Ethernet interface, for communication with the server.

\subsection{Robot}

The robot consists of a Lego Mindstorms robot, and uses a JVM NXT Brick for running the software, two motors (A and B) to run operate the wheels that handle the movement of the robot, another motor (C) that rotates a sensor for scanning the environment, and an Ultrasound sensor, connected to Port 1.

\subsubsection{Robot hardware design}

The robot hardware design is displayed in figure \ref{fig:robothw}.

\begin{figure}[h!]
\includegraphics[width=0.5\textwidth] {bilder/IMG_1434.jpg}
\includegraphics[width=0.5\textwidth] {bilder/IMG_1435.jpg}
\includegraphics[width=0.5\textwidth] {bilder/IMG_1436.jpg}
\includegraphics[width=0.5\textwidth] {bilder/IMG_1438.jpg}
\caption{The robot.}
\label{fig:robothw}
\end{figure}

\section{Software}

To implement the system, the group chose to use Java in all parts of the system. To run Java applications on the NXT Brick, it's operating system had to be replaced with the LeJOS platform, which includes a Java VM.

\subsection{Server}

An UML diagram for the server can be found in figure \ref{fig:serversw}.

\begin{figure}[h!]
\includegraphics[width=0.8\textwidth] {bilder/PC.png}
\caption{The server UML diagram.}
\label{fig:serversw}
\end{figure}


\subsection{Client}

An UML diagram for the client can be found in figure \ref{fig:clientsw}.

\begin{figure}[h!]
\includegraphics[width=0.5\textwidth] {bilder/Client.png}
%\missingfigure{Client UML}
\caption{The client UML diagram.}
\label{fig:clientsw}
\end{figure}


\subsection{Robot}

An UML diagram for the robot can be found in figure \ref{fig:robotsw}.

\begin{figure}[h!]
\includegraphics[width=0.8\textwidth] {bilder/NXT.png}
\caption{The robot UML diagram.}
\label{fig:robotsw}
\end{figure}

\subsection{Communication protocols}

\subsection{Server-robot communications}

An intergroup meeting was held were a common protocol was agreed on. The protocol is a XML structure that in it's most basic form must have 4 commands that all groups need to support; move, rotate, scan and reboot. All communications to the robot are acknowledged by a return message that contains the data sent to the robot, and the responses to that message. Only the messages that are relevant for the current communication needs to be sent, that means, if you want to move, you do not have to send a "rotate 0 degrees" command.

The protocol can be expanded by each group by adding own commands to it. The new commands must have names in the form \emph{GXname}, where X is the group number and name is the name of the command.

Group 2 has added the command G2close which is used to signal the robot that the connection will be broken, and G2automode which starts the autopilot that does an initial scan of the environment.

If the connection is lost between the robot and the server, the robot waits for a new connection in the current position. The robot will not do anything active to regain contact with the server. This will be changed in the forthcoming development.

The protocol looks like this:

\subsubsection{Server-to-robot protocol}

\begin{lstlisting}[language=XML]
<?xml version="1.0" encoding="utf-8"?>
<s2r>
	<move req=""/>
	<rotate req=""/>
	<scan n=""/>
	<reboot/>
	<G2close/>
</s2r>
\end{lstlisting}

\[
\begin{tabular}{c |c | l}
Command & Parameters & Description \\
\hline
move & req & Moves the robot \emph{req} cm. Positive values move the robot forward,\\ 
&& negative backward. \\
rotate & req & Rotates the robot \emph{req} degrees. Positive values moves the robot \\
&& clockwise, negative counter clockwise. \\
scan & n & Makes the robot use the US sensor to measure distance in \emph{n} directions,\\
&& the angle between every direction being the same. \\
reboot & N/A & Reboots the robot. \\
G2close & N/A & Initializes bluetooth connection termination. \\
\end{tabular}
\]

\subsubsection{Robot-to-server protocol}


\begin{lstlisting}[language=XML]
<?xml version="1.0" encoding="utf-8"?>
<r2s>
	<move req="" real=""/>
	<rotate req="" real=""/>
	<scan n="" n1="" n2="" n3="" (...) nN=""/>
	<reboot/>
	<G2close/>
</r2s>
\end{lstlisting}

\[
\begin{tabular}{c |c | l}
Command & Parameters & Description \\
\hline
move & req, real & Acknowledges the request to move \emph{req} cm, and reports \\
&& the actual movement to be \emph{real} cm. \\
rotate & req, real & Acknowledges the request to rotate \emph{req} degrees, and \\
&& reports the actual movement to be \emph{real} degrees. \\
scan & n, n1, n2, n3, ... nN & Acknowledges the request to measure in \emph{n} directions, \\
&& and returns all the \emph{nN} points. \\
reboot & N/A & Acknowledges reboot command recieved. \\
G2close & N/A & Acknowledges connection termination command\\
&& recieved. \\
\end{tabular}
\]

\subsection{Client-server communication}

The client uses the same protocol as the server-robot interface to send the actual commands. It also implements a new command that starts the server side control of the robot to map the environment. This means that the protocol from the client to the server looks as follows:


\[
\begin{tabular}{c |c | l}
Command & Parameters & Description \\
\hline
move & req & Moves the robot \emph{req} cm. Positive values move the robot forward,\\ 
&& negative backward. \\
rotate & req & Rotates the robot \emph{req} degrees. Positive values moves the robot \\
&& clockwise, negative counter clockwise. \\
scan & n & Makes the robot use the US sensor to measure distance in \emph{n} directions,\\
&& the angle between every direction being the same. \\
reboot & N/A & Reboots the robot. \\
G2close & N/A & Initializes bluetooth connection termination. \\
G2autopilot & N/A & Starts the initial scan of the environment. \\
\end{tabular}
\]

While all of these are supported by the underlying protocol, the client application only implements the movement, scan and autopilot methods in the interface.

The client and server protocol also handles the sending of map and webcam data from server to client. The communications is done via Ethernet, using TCP port 4444. The first thing the client sends to the server is also information about which robot to connect to, using a simple text string, "robotname:\emph{name}".

Both the map and webcam images are sent as JPEG images. The first bit of the image stream notifies the client which of the pictures are being sent, and the next 32 bits contain the size of the image. The rest of the stream contains the image itself.

\[
\begin{tabular}{c | l }
Bit & Description \\
\hline
0 & The first bit is 0 for map image and 1 for webcam image. \\
1-32 & The size of the image being sent. \\
33-EOS & The image in JPEG format. \\
\end{tabular}
\]

The client does not send any acknowledgements to the server at this point, but this is supposed to be implemented during future work.

\end{document}